---
title: Tiling Plugin
description: A performance-enhancing plugin that renders pages in smaller tiles for faster zooming and panning on large documents in Vue.
searchable: true
---

# Tiling Plugin

The Tiling Plugin is a **performance optimization** that can dramatically improve the user experience for large documents or at high zoom levels.

Instead of rendering a page as one large image, this plugin breaks it into a grid of smaller tiles. It then intelligently renders only the tiles currently visible in the viewport, reducing memory usage and speeding up render times. This technique is similar to how online maps work, loading content as you pan and zoom.

## Installation

The plugin depends on the `Render`, `Scroll`, and `Viewport` plugins. You must install all four packages.

```sh npm2yarn
npm install @embedpdf/plugin-tiling @embedpdf/plugin-render @embedpdf/plugin-scroll @embedpdf/plugin-viewport
````

## Registration

Import `TilingPluginPackage` and its dependencies, and add them to the `plugins` array. The Tiling plugin should be registered after the plugins it depends on.

```typescript {6, 16-20}
import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/vue'
import { ScrollPluginPackage } from '@embedpdf/plugin-scroll/vue'
import { RenderPluginPackage } from '@embedpdf/plugin-render/vue'
import { TilingPluginPackage } from '@embedpdf/plugin-tiling/vue'

const plugins = [
  // ... other essential plugins
  // Register dependencies first
  createPluginRegistration(ViewportPluginPackage),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),

  // Register and configure the tiling plugin
  createPluginRegistration(TilingPluginPackage, {
    tileSize: 768,
    overlapPx: 5,
    extraRings: 1, // Pre-render one ring of tiles outside the viewport
  }),
]
```

## Usage

The best way to use the Tiling plugin is to adopt a two-layer rendering strategy. This provides the best user experience by showing a fast, low-resolution preview immediately, then progressively enhancing it with high-resolution tiles.

You achieve this by rendering **both** a `<RenderLayer />` and a `<TilingLayer />`:

1.  **`<RenderLayer />`**: Use this for the base layer. Give it a low, fixed `scale` prop (e.g., `0.5` or `1`) so it renders a blurry but complete preview of the page very quickly.
2.  **`<TilingLayer />`**: Place this on top of the base layer. It receives the dynamic `scale` prop from the scroller and will render the crisp, high-resolution tiles over the blurry preview.

```vue
<script setup lang="ts">
import { RenderLayer } from '@embedpdf/plugin-render/vue';
import { TilingLayer } from '@embedpdf/plugin-tiling/vue';
</script>

<template>
  <Scroller>
    <template #default="{ page }">
      <div :style="{ width: `${page.width}px`, height: `${page.height}px`, position: 'relative' }">
        <RenderLayer :page-index="page.pageIndex" :scale="1" />
        <TilingLayer :page-index="page.pageIndex" :scale="page.scale" />
      </div>
    </template>
  </Scroller>
</template>
```

## Live Example

This example uses the `<TilingLayer />` for rendering. Zoom in significantly on the document to see the tiles being rendered individually. You may notice a brief low-resolution version of a tile before the high-resolution version loads in.

import { TilingExample } from '../code-examples/tiling-example';

<TilingExample />

## API Reference

### Configuration (`TilingPluginConfig`)

| Option | Type | Description |
| :--- | :--- | :--- |
| **`tileSize`** | `number` | The width and height of each square render tile in screen pixels. Larger tiles mean fewer draw calls but higher memory per tile. <br />**Default**: `768` |
| **`overlapPx`** | `number` | The number of pixels each tile should overlap its neighbors to prevent visible seams between them. <br />**Default**: `2.5` |
| **`extraRings`** | `number` | The number of "rings" of tiles to pre-render outside the visible viewport. A value of `1` or `2` can make scrolling feel smoother at the cost of more rendering. <br />**Default**: `0` |

### Component: `<TilingLayer />`

The component that orchestrates the rendering of individual tiles for a page.

| Prop | Type | Description |
| :--- | :--- | :--- |
| **`pageIndex`** | `number` | **(Required)** The index of the page for which to render tiles. |
| **`scale`** | `number` | **(Required)** The current scale of the page, used to calculate which tiles are visible and their resolution. |